@thallylabs/migrate 0.2.7 → 0.2.9

package/README.md

@@ -49,12 +49,38 @@ computes redirects dynamically and can't be evaluated statically, so its
 presence is reported with a warning instead of being silently ignored. A
 static `--ifm-color-primary` accent color in the classic theme's `customCss`
 file is imported the same way Mintlify's and Fern's theme colors are.
+Versioned docs under `versioned_docs/` and translated docs under
+`i18n/<locale>/docusaurus-plugin-content-docs/` are imported with their
+navigation, including locale-prefixed routes such as `/fr/...`. Each version
+and locale keeps its own route tree; sidebar entries without source documents
+are reported.
+Docusaurus heading ID comments such as `{/* #custom-id */}` become explicit
+HTML anchors so links to those headings keep working after migration. Links
+using Docusaurus' implicit heading slugs also get explicit aliases when the
+linked heading or option-table field can be matched uniquely. Repeated option
+fields use the nearest preceding row when all local references agree;
+otherwise ambiguous anchors remain warnings.
+Longer fenced code examples keep nested shorter fences inert. An archived
+admonition missing its closing delimiter is closed before the next top-level
+heading (or at the end of the page) so its remaining content stays importable.
+Docusaurus `mdx-code-block` wrappers are opened as live MDX when the resulting
+page compiles and its special fences contain no module declarations. Pages
+whose fragments still need Docusaurus theme imports or remark plugins remain
+fenced and are retained.
 
 Fern repositories are located by their `fern/docs.yml` + `fern/fern.config.json`
 pair. `docs.yml` is parsed as bounded YAML—never executed—and preserves tabs,
 nested sections (including `slug`/`skip-slug`), navbar links, redirects, the
 default Fern version's navigation, and theme accent colors. Only pages
 referenced from `docs.yml` are imported, matching Fern's own publishing model.
+Versioned `folder:` entries expand the Markdown files they contain, even when
+the folder or an individual page is outside `fern/` but still inside the
+checkout. An explicit empty tab `slug` keeps pages at the site root; a folder
+title changes its navigation label without changing its directory-based URL.
+Internal links are adjusted for the site's domain path, selected version, and
+source-file routes. Links to sections not imported into Thally stay on the
+published Fern site and produce a migration warning, so the generated site can
+build while the remaining content is moved separately.
 Every `api:` section's OpenAPI document is resolved from its own
 `generators.yml` (`api.specs[].openapi`, or the legacy `api:` string) and
 imported into its own tab — a docs.yml with several API sections (e.g. a REST
@@ -112,8 +138,16 @@ The importer creates a root redirect to the first available page in source
 navigation when no root introduction exists, while retaining a separate custom
 homepage and explicit redirects. Locale tags and recognized locale-prefixed
 sections are normalized without discarding original URL redirects.
+Mintlify's generated `param-*` links for settings headings and named fields
+become explicit anchors in migrated MDX.
 
 Simple interactive HTML blocks in MDX are extracted into client components.
+For a copied client component that receives a simple page-authored JSX callback,
+the importer moves the callback into a client wrapper and keeps the page. If
+the callback cannot be moved safely, it keeps the page and the control's child
+content as a passive fallback, with a warning identifying the control. A
+stateful local snippet component is kept as a client component instead of
+flattening away its hooks and state.
 The Mintlify `search-bar-entry` click trigger is mapped to Thally's search
 shortcut. Markdown mixed inside interactive JSX, computed imports, and
 namespace imports are reported for manual review; unsupported source is
@@ -135,11 +169,9 @@ overrun), with a warning naming the page and the component. Packages the starter
 kept as-is (except `react-dom/server`, whose string renderers throw under
 Next) and copied into any extracted client module. A source site's own
 `@/…` path aliases are treated like an unavailable package. A page that
-passes a page-authored function (including a class, or a function written as
-children) as a prop into a component confirmed to cross the server/client boundary (one this
-importer extracted as a client module, or a Thally runtime built-in already
-backed by one, such as `Accordion`/`Panel`/`Tabs`) is excluded the same way;
-an unconfirmed target is warned instead of dropped.
+passes a page-authored function into a client component needs the client
+wrapper described above; unsupported callback shapes retain their content
+with a warning. An unconfirmed target is warned for review.
 File paths cannot escape the repository checkout; symlinks and oversized
 graphs are rejected. This is compatibility analysis, **not a code sandbox**:
 imported JavaScript executes when the developer builds or runs the resulting

package/dist/index.d.ts

@@ -41,13 +41,23 @@ interface MigrationNavbarConfig {
         href: string;
         type?: 'github';
     }>;
+    /** Explicit null suppresses the starter's sample call to action. */
     primary?: {
         label: string;
         href: string;
+    } | null;
+    /** Local public assets used until an owner uploads a brand replacement. */
+    logo?: {
+        light: string;
+        dark?: string;
+        showTitle?: boolean;
+        rightText?: string;
     };
 }
 interface MigrationFooterConfig {
     socials?: Record<string, string>;
+    /** Literal footer attribution; `{year}` is resolved by the site at render time. */
+    copyright?: string;
     links?: Array<{
         heading: string;
         items: Array<{
@@ -72,6 +82,10 @@ interface MigrationDocsConfig {
     };
     banner?: MigrationBannerConfig;
     navbar?: MigrationNavbarConfig;
+    favicon?: {
+        light: string;
+        dark?: string;
+    };
     footer?: MigrationFooterConfig;
     seo?: {
         indexing?: 'navigable' | 'all';
@@ -111,6 +125,8 @@ interface MigrationDocsConfig {
             code: string;
             label: string;
         }>;
+        /** Source-authored navigation labels and ordering for each translation. */
+        navigation?: Record<string, Array<MigrationNavigationTab>>;
     };
 }
 interface MigrationPage {
@@ -122,6 +138,8 @@ interface MigrationPage {
     title: string;
     navTitle?: string;
     description: string;
+    /** Keep SEO/search description without repeating it above Docusaurus body copy. */
+    descriptionPlacement?: 'body';
     badge?: string;
     keywords: Array<string>;
     mode?: 'default' | 'wide' | 'custom' | 'center' | 'home';
@@ -221,6 +239,8 @@ interface RepositoryMigrationOptions {
     docusaurusSkipPlugins?: boolean;
     /** @internal Additional docs plugins default to autogenerated navigation. */
     docusaurusSkipSidebar?: boolean;
+    /** @internal A version's sidebar is parsed as static data. */
+    docusaurusSidebarPath?: string;
     /** @internal Static assets are shared across docs-plugin instances. */
     docusaurusSkipAssets?: boolean;
     /** @internal Redirects are global config, read once, not per plugin instance. */
@@ -310,6 +330,10 @@ interface FernPageDescriptor {
     /** Path to the referenced page file, relative to the Fern root. */
     sourcePath: string;
     navigationId: string;
+    /** Fern's sidebar label can intentionally differ from the page title. */
+    navTitle?: string;
+    /** Keep routable pages excluded by Fern's `hidden` navigation flag. */
+    hidden?: boolean;
 }
 /** One `api:` navigation node, resolved to the name/tab Thally needs to bind its spec. */
 interface FernApiSection {
@@ -335,6 +359,11 @@ interface FernNavigationResult {
     warnings: Array<MigrationWarning>;
     /** Every `api:` node found in navigation, in document order. A repo can declare several (e.g. a REST and a WebSocket API in separate tabs). */
     apiSections: Array<FernApiSection>;
+    /** Fern changelog tabs render their entries as a feed at the bare route. */
+    changelogIndexes: Array<{
+        route: string;
+        entries: Array<string>;
+    }>;
 }
 /** Read `fern/docs.yml` without executing anything. */
 declare function readFernConfig(fernRoot: string): {
@@ -345,6 +374,7 @@ declare function readFernConfig(fernRoot: string): {
 declare function projectFernNavigation(input: {
     config: Record<string, unknown>;
     fernRoot: string;
+    repositoryRoot?: string;
 }): FernNavigationResult;
 
 /** Markdown/MDX normalization that preserves every component Thally supports. */
@@ -355,7 +385,7 @@ interface MarkdownPageIdentity {
     locale?: string;
 }
 /** Normalize only syntax Thally cannot render; supported source JSX stays intact. */
-declare function normalizeMdx(body: string, platform?: MigrationPlatform): string;
+declare function normalizeMdx(body: string, platform?: MigrationPlatform, unwrapMdxCodeBlocks?: boolean): string;
 /** Parse source Markdown or MDX into the canonical page representation. */
 declare function parseMarkdownPage(input: {
     id: string;